Language/OS - Multiplatform Resource Library

home *** CD-ROM | disk | FTP | other *** search

/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / cpp_libs / cool / ge_cool.lha / GE_COOL2.1 / man / oldman3 / Association.3T < prev next >

Wrap

Text File | 1992-06-29 | 10.1 KB | 335 lines

.TH ASSOCIATION .SH NAME Association<Ktype,Vtype>\f1 A dynamic, parameterized association .SH SYNOPSIS #include <cool/Association.h> .SH DESCRIPTION The \f3Association<Ktype,Vtype>\f1 class is privately derived from the \f3Vector<Type>\f1 class and implements a collection of pairs. The first of the pair is called the key , and the second of the pair is called the value . The \f3Association<Ktype,Vtype>\f1 class implements a one-dimensional vector parameterized over a pair of objects. The first type specifies the type of the key, and the second type specifies the type of the value. Many of the member functions for \f3Association<Ktype,Vtype>\f1 are inherited from \f3Vector<Type>\f1 and, consequently, are inline calls to the vector member function of the same name. .PP The \f3Association<Ktype,Vtype>\f1 class inherits the dynamic growth capability of the Vector class. Vectors are, by default, dynamic in nature. A static-sized vector object is selected by setting the growth allocation size to zero or by passing in a pointer to a block of user-supplied storage to the constructor. If a vector is of static size and an operation is performed that requires more storage, an \f3\f3Error\f1\f1 exception is raised. .PP The \f3Association<Ktype, Vtype> \f1class implements the notion of a current position. This is useful for iterating through the elements of a vector. The current position is maintained in a data member of type Association_state and is set or reset by all member functions affecting elements in the class. Member functions are provided to reset the current position, move to the next and previous elements, find an element, and get the value at the current position. The \f3Iterator<Type>\f1 class provides a mechanism to save and restore the state associated with the current position, thus allowing the programmer to use multiple iterators over the same instance of an association object. .SH Base Classes \f3Vector<Type>, Vector, .SH Friend Classes None .SH Constructors .TP \f3Association<Ktype,Vtype> ();\f1 Creates an empty association of the specified type. .TP \f3Association<Ktype,Vtype> (const Association<Ktype,Vtype>& \f3assoc);\f1 Duplicates the size and value of an association object. .TP \f3Association<Ktype,Vtype> \f3(unsigned long \f2number);\f1 Allocates enough storage for an association of a specific type to hold number elements. .TP \f3Association<Type> (void* \f2storage\f3, unsigned long \f2number\f3);\f1 Creates a static-sized association object for number elements whose storage storage is provided by the user. If an object of this type attempts to grow dynamically or the programmer invokes the resize member function, an \f3\f3Error\f1\f1 exception is raised. .SH Member Functions .TP inline long capacity (); Returns the maximum number of elements the association can contain. .TP inline void clear () Removes all elements in the object and invalidates the current position. .TP inline Association_state& current_position (); Returns the state information associated with the current position. This function should be used with the \f3Iterator<Type>\f1 class to save and restore the current position, thus facilitating multiple iterators over an instance of association. .TP \f3Boolean find (const Ktype& key\f3);\f1 Searches the association for key . If found, this function sets the current position and returns TRUE ; otherwise, this function resets the current position and returns FALSE . .TP \f3Boolean get (const Ktype& key, Vtype& value\f3);\f1 Gets the associated value for key . This function returns TRUE and modifies value to contain the associated value. If key is not found, this function returns FALSE and does not modify value . .TP \f3Boolean get_key (const Vtype& value, Ktype& key\f3) const;\f1 Gets the first associated key for value . This function returns TRUE and modifies key to contain the associated key. If value is not found, this function returns FALSE and does not modify key . .TP \f3inline const Ktype& \f3key () const;\f1 Returns the key of the key/value pair at the current position. .TP inline long length (); Returns the number of elements (pairs) in the association. .TP inline Boolean next (); Advances the current position pointer to the next element in the association and returns TRUE . If the current position is invalid, this function advances to the first element and returns TRUE . If advancing past the last element, this function invalidates the current position and returns FALSE . .TP \f3Association<Ktype,Vtype>& \f3operator= (const Association<Ktype,Vtype>>>&\f3);\f1 Overloads the assignment operator for the Association class and assigns one association object to have the value of another by duplicating the size and element values. This function invalidates the current position. If the association is prohibited from dynamically growing as necessary, an \f3\f3Error\f1\f1 exception is raised. .TP \f3Boolean operator== (const Association<Ktype,Vtype>& assoc\f3) const;\f1 Overloads the equality operator for the Association class. This function returns TRUE if the associations have the same number of elements with the same values; otherwise, this function returns FALSE . .TP \f3inline Boolean operator!= (const Association<Ktype,Vtype>& assoc\f3) const;\f1 Overloads the inequality operator for the Association class. This function returns TRUE if the associations have a different number of elements or different values; otherwise, this function returns FALSE . .TP inline Boolean prev (); Moves the current position pointer to the previous element in the association and returns TRUE . If the current position is invalid, this function moves to the last element and returns TRUE . If moving to the previous element passes the first element in the association, this function invalidates the current position and returns FALSE . .TP \f3Boolean put (const Ktype& key\f3, const Vtype& value\f3);\f1 Puts the key/value pair into the association. If a pair already exists with the specified key, the value for that pair is replaced with value . If required and not prohibited, the association is grown. If the new pair is successfully put into the association, TRUE is returned; otherwise, FALSE is returned. .TP Vtype& remove (); Removes and returns a reference to the element at the current position. This function sets the current position to the element immediately following the element removed. If the element removed is at the end of the association, this function invalidates the current position. If the current position is invalid, and \f3\f3Error\f1\f1 exception is raised. .TP \f3Boolean remove (const Ktype& key\f3);\f1 Searches for key and, if found, this function removes the pair associated with key and sets the current position to the element immediately following the element removed; then, the function returns TRUE . If key is found at the end of the association, this function invalidates the current position and returns TRUE . If key is not found, this function returns FALSE . .TP inline void reset (); Invalidates the current position. .TP \f3inline void resize (long \f2number\f3);\f1 Resizes the association for at least number elements. If a growth ratio has been selected and it satisfies the resize request, the association is grown by this ratio. This function invalidates the current position. If the size specified is zero or negative, an \f3\f3Error\f1\f1 exception is raised. .TP \f3inline void set_alloc_size (int \f2size\f3);\f1 Updates the allocation growth size to be used when the growth ratio is zero. Default allocation growth size is 100 bytes. If the size specified is negative, an \f3\f3Error\f1\f1 exception is raised. .TP \f3inline void set_growth_ratio (float \f2ratio\f3);\f1 Updates the growth ratio for this instance of an association to the specified value. When an association needs to grow, the current size is multiplied by the ratio to determine the new size. If ratio is negative, an \f3\f3Error\f1\f1 exception is raised. .TP \f3void set_key_compare (\f2Assoc_Key_Compare \f3= NULL);\f1 Updates the key compare function for this class of association. Assoc_Key_Compare is a function of type Boolean (\f2*Function\f1)(\f3const Type&\f1, \f3const Type&\f1). If no argument is provided, the operator== for Ktype over which the key for the association class is parameterized is used. .TP \f3inline long set_length (long \f2number\f3);\f1 Specifies the number of elements in an association to allow random access via the overloaded operator[\^] member function. If number is larger than the storage allocated, this function truncates number to the largest value the allocated size will support. This function returns the updated number of elements. .TP \f3void set_value_compare (\f2Assoc_Value_Compare \f3= NULL);\f1 Updates the value compare function for this class of association. Assoc_Value_Compare is a function of type Boolean (\f2*Function\f1)(\f3const Ktype&\f1, \f3const Vtype&\f1). If no argument is provided, the operator== for Vtype over which the value for the association class is parameterized is used. .TP inline Vtype& value (); Returns a reference to the value of the key/value pair at the current position. .SH Friend Functions .TP \f3friend ostream& operator<< (ostream& \f2os,\f3 const Association<Ktype,Vtype>& assoc\f3);\f1 Provides a formatted output capability for reference to an \f3Association<Ktype,Vtype>\f1 object. .TP \f3inline friend ostream& operator<< (ostream& \f2os\f3, const Association<Ktype,Vtype>* assoc\f3);\f1 Provides a formatted output capability for a pointer to an \f3Association<Ktype,Vtype>\f1 object. .SH COPYRIGHT Copyright (C) 1991 Texas Instruments Incorporated. Permission is granted to any individual or institution to use, copy, modify, and distribute this software, provided that this complete copyright and permission notice is maintained, intact, in all copies and supporting documentation. Texas Instruments Incorporated provides this software "as is" without express or implied warranty.